/*
 * Copyright (c) 2009, Jan Stender, Bjoern Kolbeck, Mikael Hoegqvist,
 *                     Felix Hupfeld, Felix Langner, Zuse Institute Berlin
 * 
 * Licensed under the BSD License, see LICENSE file for details.
 * 
 */

package org.xtreemfs.babudb.lsmdb;

import java.util.Iterator;
import java.util.Map.Entry;

import org.xtreemfs.babudb.BabuDBException;
import org.xtreemfs.babudb.BabuDBRequestResult;
import org.xtreemfs.babudb.UserDefinedLookup;

public interface DatabaseRO {
    
    /**
     * <p>
     * Lookup a single key.
     * Return value will contain a view buffer to the result or null if there 
     * is no such entry. 
     * </p>
     *
     * @param indexId
     *            index id (0..NumIndices-1)
     * @param key
     *            the key to look up
     * @param context
     *            arbitrary context which is passed to the listener.
     * @return a future as proxy for the request result.
     */
    public BabuDBRequestResult<byte[]> lookup(int indexId, byte[] key, 
            Object context);
    
    /**
     * <p>
     * Executes a prefix lookup.
     * Return value will contain an iterator to the database starting at the 
     * first matching key. Returns key/value pairs in ascending order.
     * </p>
     *
     * @param indexId
     *            index id (0..NumIndices-1)
     * @param key
     *            the key to start the iterator at
     * @param context
     *            arbitrary context which is passed to the listener.
     * @return a future as proxy for the request result.
     */
    public BabuDBRequestResult<Iterator<Entry<byte[], byte[]>>> prefixLookup(
            int indexId, byte[] key, Object context);
    
    /**
     * <p>
     * Executes a reverse prefix lookup. 
     * Return value will contain an iterator to the database starting at the 
     * first matching key. Returns key/value pairs in descending order. 
     * </p>
     * 
     * @param indexId
     *            index id (0..NumIndices-1)
     * @param key
     *            the key to start the iterator at
     * @param context
     *            arbitrary context which is passed to the listener.
     * @return a future as proxy for the request result.
     */
    public BabuDBRequestResult<Iterator<Entry<byte[], byte[]>>> reversePrefixLookup(
            int indexId, byte[] key, Object context);
    
    /**
     * <p>
     * Performs a user-defined lookup.
     * Return value will contain the result generated by the user 
     * defined lookup method.
     * </p>
     * 
     * @param udl
     *            the method to be executed
     * @param context
     *            arbitrary context which is passed to the listener.
     * @return a future as proxy for the request result.
     */
    public BabuDBRequestResult<Object> userDefinedLookup(UserDefinedLookup udl, 
            Object context);
    
    /**
     * Shuts down the database.
     * 
     * @attention: does not create a final checkpoint!
     */
    public void shutdown() throws BabuDBException;
    
}
